<body>
This package contains utility classes and in particular: 
<ul>
<li>classes for handling properties,
<li>the <a href="Logger.html">Logger</a> class for logging capabilities;
<li>the leap subpackage, that is a replacement for
the Java collection framework that is not supported by J2ME.

<p><b> HANDLING PROPERTIES</b><br>
These property classes provide a convenient method to easily provide an agent with configuration data.
For example, the following would be usable in any agent running in an environment supporting ExpandedProperties:

<pre>
     // Add and initialize the following in your agent.
     protected myProperties = new ExpandedProperties();

     // Called by JADE with any arguments given to the agent from the command line.
     public void setArguments(String[] args) {
         myProperties.parseArgs(args);
         // myPropeties may now be used throughout your agent code.
         // See the class BasicProperties for all its easy to use getters.
     }
</pre>
Properties are of the form: <b>key=value</b> or <b>key:value</b>.
The special property <b>import:foo.properties</b> causes the property file <b>foo.properties</b> to be read.
The ".properties" suffix is simply a common convention and is not required or enforced by these
classes. One property file may import from others. Circular imports are checked for and if detected will throw
a PropertiesException (extension of RuntimeException). Here is an example of a properties file:
<pre>
     # Specifies one or more user IDs to notify.
     # Separate each with a space.
     jabber.notify=smith
     # The Jabber server.
     jabber.server=theserver.hpl.hp.com

     SimpleCalendar.input=${AGENT_HOME}/config/simplecalendar.properties
     weather.state=CA
     weather.city=MOFFETT ARPT
     weather.zonecode=CAZ006
</pre> 
Property files may contain as many pairs as necessary. Blank lines as well as lines
beginning with '#' or '!' are ignored. A line ending with '\' is interpreted as continued
to the next line. Within a collection of continued lines, any beginning with '#' or '!' are
ignored making it easy to comment out particular ones.
<p>
To fetch the value associated with a key, use the format <b>${xxx}</b>. An all uppercase key, such
as <b>${AGENT_HOME}</b> in the above example will cause the environment space (full not just those
in the JVM's System properties) to be checked if the key doesn't exist in the properties collection.
<p>
A property may be set such that it can't be altered by ending the key value
with a '!'. For example:
<pre>
     agentClass!=com.hp.agent.Foo
</pre>
One still references this property as ${agentClass}. This is particularly handy when you want to make a property
collection available but prevent the changing of particular values. We have used this in conjunction with
loading a property collection from the same jar file as a particul class. This is demonstrated below:
<pre>
    String defaultPropName = "com/hp/agent/smartagent/setup.properties";
    properties = new ExpandedProperties();
    InputStream propertyStream = this.getClass().getClassLoader().getResourceAsStream(defaultPropName);
    if (propertyStream != null) {
        try {
            properties.load(propertyStream);
        } catch (IOException ioe) {
            throw new PropertiesException("Error reading:" + defaultPropName);
        }
    }
</pre>
<p>
Consult each classes documentation for further information but they
relate as follows:
<ol>
<li><b>BasicProperties</b> - This class provides the foundation class. It
is designed to be usable in the restrictive J2ME CLDC environment. It
provides enhanced property management as well as providing support for
values containing strings of the form <b>${xxx}</b>.
To increases the portability of your property files, it provides useful default handling for common cases.
For example, when the value of a property whose key name has the string "path" as part of it
(ex: "classpath", "sourcepath", "mypath") is fetched any occurance of '|' will be converted to
the value from System.getProperty("path.separator").
<li><b>ImportableProperties</b> - This abstract class extends BasicProperties and
serves as a basis for supporting the ability to import properties from files.
Those files may also contain further import directives. It is also usable in
the restrictive J2ME CLDC environment. Since file support will be handled
differently in different environments, it contains one abstract method
<b><tt>fileReader</tt></b> which given the name of a file (its URL) must
return a Reader object. Extending classes will provide that method in a
suitable fashion. For example, in the desktop world this would be:
<pre>
     return new InputStreamReader(new FileInputStream(aFileName));
</pre>
whereas in the CLDC environment it would be:
<pre> 
     return new InputStreamReader(Connector.openInputStream(aFileName));
</pre>
<li><b>EnhancedProperties</b> - Provides a concrete implementation of ImportableProperties
useable in the J2SE (desktop) world.
<li><b>ExpandedProperties</b> - Extends EnhancedProperties and adds support for fetching
system environment variables (those usable from the OS shell). This class would need
to be carefully considered in different environments. When a key is <u>all uppercase</u> we first
attempt to fetch its value from the property collection and if not found there then from
the systems environment space. With this class you may fetch <b>all</b> environment variables,
not just those the JVM puts into its System properties collection.
<li><b>PropertiesException</b> - Extends RuntimeException and is thrown under various
error conditions by these classes.
</ol>
</body>
